home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / dpmi_lib.zip / DPMI.TXT < prev    next >
Text File  |  1991-11-06  |  11KB  |  290 lines
  1. The C-Library for DPMI-Specification 0.9 and Protected Mode
  2.  
  3. This is a short documentation for the interface functions. For details, read the
  4. DPMI-specification 0.9 . Protected Mode is discribed in some special books like
  5. Ray Duncan "Extended Dos".
  6.  
  7. This library allows DOS-programs to run in protected mode.The great advantage is
  8. the big address space. You can use the DPMI Interface 0.9 functions only in
  9. enhanced mode in Windows 3.0 . In standard mode the function real_to_protected
  10. is not supported. So you can't use the other funtion using int 31H.
  11. A 286 computer can only use DPMI-functions in a Window-program, but i don't know
  12. if this is useful.I hope other programs will support the DPMI-Interface.
  13.  
  14. The most compiler run in 16-bit mode. The limit for the selectors should be
  15. set to 64KB. The functions extmalloc for example creates a continue array of
  16. selectors if you allocate more than 64KB. This is neccesary, because you can't
  17. address the whole space with a 16-bit compiler pointer,if you have only one
  18. descriptor(limit more than 64KB). The library can be modified to run 32-bit
  19. programs.
  20.  
  21. There are some printf statements in the protected mode code. This is allowed, 
  22. because Windows provides a DOS-Extender.In other Environments this may be not
  23. and you must write a protected mode handler for int 21h.
  24.  
  25. The library is not complete. Some of the DPMI 0.9 functions miss here.
  26. In a next update i will complete it.
  27. The c-code is for TurboC/Tasm but there are only few special TurboC statements.
  28. Look in the files 'dpmiutil.c' and 'dpmi.h'.
  29.  
  30. Execute the files in the DosBox or from the File-manager. Be sure that the
  31. PIF-files are there. This is neccessary because program memory must be locked.
  32. Don't execute from the Turbo-Shell. This can cause a system-crash.
  33.  
  34. Files include in dpmi_lib.zip:
  35.  
  36.         dpmi.txt      : this file
  37.         dpmiutil.c    : Main C-file include the Dpmi/PM -library
  38.         dpmiutil.obj  : Object-file
  39.         dpmi.h        : Header file for dpmi programs
  40.         dpmi_v1.exe   : Demo 1 : shows the System-Tables used in Protected Mode
  41.         dpmi_v1.c     : sources demo1
  42.         dpmi_v1.mak   : Makefile demo1
  43.         dpmi_v1.pif   : Windows 3.0 386/PIF-file for demo1
  44.         dpmi_v2.exe   : Demo 2 : memory info and test program
  45.         dpmi_v2.c     : sources demo2
  46.         dpmi_v2.mak   : Makefile demo2
  47.         dpmi_v2.pif   : Windows 3.0 386/PIF-file for demo2
  48.  
  49. If you already work with protected mode or you have some questions send mail to
  50.  
  51. Email Number : rainer@math5.uni-bielefeld.de
  52.  
  53. Home Address: Rainer Schnitker , Heeper Stasse 283 , 4800 Bielefeld , Germany
  54.  
  55.  
  56.  
  57. In "DPMI.H" you can find the following structures:
  58.  
  59.      1.  struct {
  60.                 WORD lim_lo,base_lo;
  61.                 BYTE base_mi,access;
  62.                 BYTE lim_hi,base_hi;
  63.                 } DESCRIPTOR ;
  64.         this is the main structure in protected mode
  65.  
  66.      2. struct {
  67.         WORD limit,lo,hi ;
  68.            } GDTR ;
  69.         this structure is used to call the instruction sgdt
  70.          ( save Global Descriptor Table )
  71.  
  72.      3. struct {
  73.         WORD off_lo;
  74.         WORD sel;
  75.         BYTE count;
  76.         BYTE type;
  77.         WORD off_hi;
  78.         } GATE;
  79.         this structure is used in the IDT
  80.  
  81.  
  82. The structure
  83.         struct { DWORD i1,i2,i3,i4,i5,i6,i7,i8,i9,r1,r2,r3 ;
  84.                }  FREEMEMINFO;
  85.  is used in DPMI memory info (see below).
  86.  
  87. The line
  88.  #define DPMI(function)  { _AX = function ; __int__(0x31) ; }
  89. calls the DPMI Interface via int 31h
  90.  
  91.  
  92. THE DPMI INTERFACE :
  93.  
  94. * CPU switching for DPMI 0.9
  95.  
  96. void real_to_protected(void);
  97.         - call this function switch the cpu in protected mode
  98.         - other funtions are not execute if this function fails
  99.         - cs,ds,es were set by the dpmi host
  100.  
  101. void protected_to_real(void);
  102.         - switch cpu back to real mode
  103.         - terminates the program ( like real mode int21,function 4c)
  104.  
  105. * LDT Descriptor management services  DPMI 0.9
  106.  
  107. WORD AllocLDT(WORD n);
  108.         - this allocates n descriptors from the Local Descriptor Table
  109.         - return value of the first selector , 0  on error
  110.         - add the value returned from function SelInc() to get the next selector
  111.         - the descriptors will be set to present data type, base=0 , limit=0
  112.  
  113. int FreeLDT(WORD selector);
  114.         - this function is used to free descriptors that were allocated
  115.           by the function AllocLDT() ,
  116.         - return    0 : successful    -1 : not successful
  117.  
  118. WORD SegtoSel(WORD realsegment);
  119.         - this converts real mode segments into descriptors
  120.         - return selector with limit 64 KB , or 0 on error
  121.  
  122. WORD SelInc(void);
  123.         - return the increment value to get the next selector (typical 8).
  124.         - function can't fail
  125.  
  126. int LockSel(WORD selector);
  127.         - undocumented function ("should not be called")
  128.         - this locks the address area of the selector
  129.         - return   0 : successful   -1 : not successful
  130.  
  131. int UnlockSel(WORD selector);
  132.         - undocumented function ("should not be called")
  133.         - this function is used to unlock the memory area
  134.         - return   0 : successful   -1 : not successful
  135.  
  136. DWORD GetBaseAddress(WORD selector);
  137.         - return the 32-bit-address of the selector , 0 on error
  138.  
  139. int SetBaseAddress(WORD selector ,DWORD 32bitaddress);
  140.         - set the base address of the specified selector
  141.         - return   0 : successful   -1 : not successful
  142.  
  143. int SetLimit(WORD sel,DWORD limit);
  144.         - set the limit for the selector
  145.         - if limit>1MB low 12 bits must be set
  146.           then the granular bit will be set
  147.         - return   0 : successful   -1 : not successful
  148.         - to get the limit use the function lsl()
  149.  
  150. int SetAccess(WORD,BYTE accessbyte,BYTE 386extendedbyte);
  151.         - set access rights for the selector
  152.         - return   0 : successful   -1 : not successful
  153.         - to get the access right use the function lar()
  154.  
  155. WORD CreatAlias(WORD codeselector);
  156.         - this creates a data descriptor with the same address and limit as
  157.           the code descriptor
  158.         - return 0 if the function was not successful
  159.  
  160. int AllocSpecialLDT(WORD selector);
  161.         - this allocates a specific LDT descriptor
  162.         - return   0 : successful   -1 : not successful
  163.  
  164. int GetDescriptor(WORD selector,DESCRIPTOR *buffer);
  165.         - this copies the 8 bytes descriptor table into the buffer
  166.         - return   0 : successful   -1 : not successful
  167.  
  168. int SetDescriptor(WORD selector,DESCRIPTOR *buffer);
  169.         - this function is used to set a descriptor
  170.         - return   0 : successful   -1 : not successful
  171.  
  172. * Interrupt Services DPMI 0.9
  173.  
  174. int GetExceptionVektor(BYTE intnumber,WORD *selector,WORD *offset);
  175.         - give the current protected mode exception handler
  176.         - return   0 : successful   -1 : not successful
  177.  
  178. int SetExceptionVektor(BYTE intnumber,WORD selector,WORD offset);
  179.         - set new protected mode exception handler
  180.         - read DPMI-specification 0.9 for some details
  181.         - return   0 : successful   -1 : not successful
  182.  
  183. int GetPMinterruptVector(BYTE,WORD *selector,WORD *offset);
  184.         - get the current protected mode interrupt handler
  185.         - return   0 : successful   -1 : not successful
  186.  
  187. int SetPMinterruptVektor(BYTE,WORD selector,WORD offset);
  188.         - set new protected mode interrupt handler
  189.         - return   0 : successful   -1 : not successful
  190.  
  191. * Memory management services DPMI 0.9
  192.  
  193. void getfreeinfo(FREEMEMINFO *);
  194.         - get struct contains free mem info
  195.  
  196. void printfreeinfo(FREEMEMINFO *);
  197.         - this prints a free memory info
  198.  
  199. DWORD GlobalAlloc(DWORD bytes,DWORD *memhandle);
  200.         - allocate memory block , size = bytes
  201.         - in Windows you get memory page granular. This means that allocation
  202.           of 534 bytes allocate 4096 = 4 KB.
  203.         - return linear address of allocated block , 0 on error
  204.         - memhandle is used to free memory blocks
  205.  
  206. int GlobalFree(DWORD memhandle);
  207.         - frees a memory block that was allocate though GlobalAlloc()
  208.         - return   0 : successful   -1 : not successful
  209.  
  210. * Page locking services DPMI 0.9
  211.  
  212. int LockLinRegion(DWORD size,DWORD linaddress);
  213.         - locks linear address range , size = region to lock
  214.         - return   0 : successful   -1 : not successful
  215.  
  216. int UnlockLinRegion(DWORD size,DWORD linaddress);
  217.         - unlock linear address range
  218.         - return   0 : successful   -1 : not successful
  219.  
  220. * other int 2F
  221.  
  222. void Yield(void);
  223.         - call int 2F function 1680h
  224.         - useful in a program loop in a multitasking environment like Windows
  225.           ( like GetMassage )
  226.  
  227.  
  228. The Protected Mode Interface:
  229.  
  230. DWORD lsl(WORD selector);
  231.         - load selector limit
  232.         - uses 32-bit commands , only for >386
  233.         - 286 must use lsl16()
  234.  
  235. WORD lsl16(WORD selector);
  236.         - load selector limit on 286 machines
  237.  
  238. WORD lar(WORD selector);
  239.         - load selector access rights
  240.  
  241. WORD verr(WORD selector);
  242.         - verify if read flags is set
  243.         - return 1 : read   0 : not
  244.  
  245. WORD verw(WORD selector);
  246.         - verify if write flag is set
  247.         - return 1 : write  0 : not
  248.  
  249. void sgdt(GDTR *gdtregister);
  250.         - save GDT base address and limit
  251.  
  252. void sidt(GDTR *idtregister);
  253.         - save IDT base address and limit
  254.  
  255. WORD sldt(void);
  256.         - save LDT selector
  257.         - return LDTselector
  258.  
  259. WORD str(void);
  260.         - save task register
  261.         - return TASKselector
  262.  
  263. * protected mode pointer
  264.  
  265. void far * incfp(void far *);
  266.         - increment descriptor to the next
  267.  
  268. void far * decfp(void far *);
  269.         - decrement descriptor to the next
  270.  
  271. void printdescriptor(DESCRIPTOR);
  272.         - print the 8 bytes from the descriptor table
  273.  
  274. void farcopy(void far *dest,void far *source,DWORD bytes)
  275.         - copy memory block from far pointer to far pointer
  276.         - bytes must min(limit-dest,limit-source) , ( -> GP-fault)
  277.         - useful to copy pointers given by extmalloc(more then 64KB)
  278.  
  279. * high level memory functions in the DPMI-Enviroment:
  280.  
  281. void far *extmalloc(DWORD nbytes);
  282.         - allocates n bytes
  283.         - if n is greater than 64 KB then continues descriptors will be
  284.           allocated. To access the next descriptor add the value return by
  285.           function IncSel() to the base selector
  286.         - return base selector , NULL if insufficient memory available
  287.  
  288. void extfree(void far *filepointer);
  289.         - frees memory that was allocated by extmalloc()
  290.